Skip to content

grpc/client: Implement Channel builder#2675

Open
nathanielford wants to merge 28 commits into
grpc:masterfrom
nathanielford:implement/channel-builder
Open

grpc/client: Implement Channel builder#2675
nathanielford wants to merge 28 commits into
grpc:masterfrom
nathanielford:implement/channel-builder

Conversation

@nathanielford

Copy link
Copy Markdown
Contributor

Introduces a type-builder Channel builder for creating new Channels, using an idiomatic pattern for adding in configuration options.

Motivation

In order to flexibly and ergonomically provide for channel configuration on construction, the type builder is introduced. This allows users to construct channels in a manner similar to:

let channel = Channel::builder("https://api.darkcave.com:443")
    .credential(my_creds)
    .runtime(my_runtime)
    .override_authority("arrow.wumpus.api")
    // ... any other options.
    .build();  // No error is returned here

Solution

The solution uses a 'type builder' so that users can build up their channel configuration over various calls, and the compiler can catch type issues. This also allows us to encapsulate various ergonomics (such as default selection of runtime). This PR implements the critical values at this time and defers additional optional values not being used until a later point. It also leaves work around the internals of the PersistentChannel/ActiveChannel for a future PR.

Because the public API is being altered, this requires a version bump.

@nathanielford nathanielford force-pushed the implement/channel-builder branch 3 times, most recently from 1014b27 to 821aa43 Compare June 11, 2026 19:50
@nathanielford nathanielford force-pushed the implement/channel-builder branch from 821aa43 to c0e1055 Compare June 11, 2026 20:01
@nathanielford nathanielford requested a review from arjan-bal June 11, 2026 20:08
@nathanielford nathanielford marked this pull request as ready for review June 11, 2026 20:08
…nChannelCredential impl adjustments should handle the type issue when passing DynChannelCredentials internally
@arjan-bal arjan-bal self-assigned this Jun 17, 2026
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/name_resolution/mod.rs Outdated
@arjan-bal

Copy link
Copy Markdown
Contributor

As discussed offline, I've raised #2694 with only the changes to the trait bounds for the credentials. I'll wait for Doug to review it.

@arjan-bal arjan-bal removed their assignment Jun 17, 2026
@arjan-bal

Copy link
Copy Markdown
Contributor

Update: #2703 has been merged to make the ChannelCredentials trait object safe. You should be able to use Arc<dyn ChannelCredentials> everywhere in builder.

@nathanielford nathanielford force-pushed the implement/channel-builder branch from a8e3dac to e197877 Compare July 6, 2026 18:41
@arjan-bal arjan-bal assigned arjan-bal and unassigned nathanielford Jul 7, 2026

@arjan-bal arjan-bal left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have left some new comments, and some of the previous feedback still needs to be addressed. Please take a look.

Comment thread grpc/src/client/name_resolution/mod.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
@arjan-bal arjan-bal assigned nathanielford and unassigned arjan-bal Jul 7, 2026
@arjan-bal arjan-bal changed the title Implement Channel builder grpc/client: Implement Channel builder Jul 7, 2026
@nathanielford nathanielford force-pushed the implement/channel-builder branch from 4288b7f to 8c1e34b Compare July 7, 2026 15:02
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
// of satisfying the credential/security configuration through different means
// in the future (via adding methods to this impl taking different args).
impl<Runtime> ChannelBuilder<MissingOpt, Runtime> {
pub fn credentials(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add rustdoc for public methods. I would also recommend using documentation tests to demonstrate the usage.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Still working on this.)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe all the doc tests are updated with this, and the public functions in channel.rs all have documentation now.

Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs
Comment thread grpc/src/client/channel.rs Outdated
@arjan-bal arjan-bal removed their assignment Jul 7, 2026
@nathanielford nathanielford force-pushed the implement/channel-builder branch from 664e2cc to fbcbbb1 Compare July 7, 2026 22:24
Comment on lines +84 to 85
#[cfg(feature = "_runtime-tokio")]
use crate::rt::default_runtime;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can remove the default_runtime function, the NoOpRuntime and directly call TokioRuntime::default() in the Channel builder constructor since it's already guarded by a feature flag now.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like to do this in a follow-up. Right now we're using it over sixteen files so I'd rather those not pollute this change with that, if that's alright?

Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs
Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
}
}

pub fn channel_authority(mut self, authority: impl Into<String>) -> Self {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should document this. You can take inspiration from Go's dial option: https://pkg.go.dev/google.golang.org/grpc#WithAuthority

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done! LMK if the language is clear enough.

Comment thread grpc/src/client/channel.rs Outdated
Comment thread grpc/src/client/channel.rs Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants